[comment {-*- tcl -*- doctools manpage}]
[comment {$Id: gpg.man 75 2014-01-10 18:36:46Z sgolovan $}]
[manpage_begin gpg n 1.0]
[copyright {2008-2014 Sergei Golovan <sgolovan@nes.ru>}]
[moddesc {Tcl interface to GNU Privacy Guard}]
[titledesc {Tcl Interface to GnuPG}]
[require Tcl 8.4]
[require Tclx]
[require gpg 1.0]
[description]
[para]

This is a Tcl interface to GNU Privacy Guard with interface similar to
TclGPGME.

[section "COMMANDS"]

[list_begin definitions]
[call [cmd set] [arg gpg] \[[cmd ::gpg::new]\]]

Create a new GPG context token.

[call [cmd "\$gpg"] [arg "free"]]

Destroy GPG token and free its resources.

[call [cmd "\$gpg"] \
      [arg "set"] \
      [arg "-property property"] \
      [opt [arg "-value value"]]]

Set or query a specified property.

The property argument may be one of the following:

[list_begin definitions]

[def "[cmd armor] [arg boolean]"]

[def "[cmd textmode] [arg boolean]"]

[def "[cmd passphrase-callback] [arg command]"]

[def [cmd "encoding"]]

[def [cmd "passphrase-encoding"]]

[list_end]

[call [cmd "\$gpg"] \
        [arg "unset"] \
        [arg "-property property"]]

Unset a specified property.

[call [cmd "\$gpg"] \
      [arg "list-keys"] \
      [opt [arg "-patterns patterns"]] \
      [opt [arg "-secretonly boolean"]] \
      [opt [arg "-command command"]]]

Return list of key tokens which match any of a specified patterns in the
patterns list [arg patterns].

[call [cmd "\$gpg"] \
      [arg "info-key"] \
      [arg "-key keytoken"]]

Return a serialized array of key properties.

[call [cmd "\$gpg"] \
      [arg "encrypt"] \
      [arg "-input input"] \
      [opt [arg "-recipients recipients"]] \
      [opt [arg "-sign boolean"]] \
      [opt [arg "-command command"]]]

Encrypt message (using either symmetric or asymmetric algorithm).

[call [cmd "\$gpg"] \
      [arg "decrypt"] \
      [arg "-input input"] \
      [opt [arg "-checkstatus boolean"]] \
      [opt [arg "-command command"]]]

Decrypt message.

[call [cmd "\$gpg"] \
      [arg "sign"] \
      [arg "-input input"] \
      [opt [arg "-mode mode"]] \
      [opt [arg "-command command"]]]

Sign message.

[call [cmd "\$gpg"] \
      [arg "verify"] \
      [arg "-signature signature"] \
      [opt [arg "-input input"]] \
      [opt [arg "-command command"]]]

Verify signature.

[call [cmd set] [arg recipient] \[[cmd ::gpg::recipient]\]]

Create recipients token.

[call [cmd "\$recipient"] \
      [arg "add"] \
      [arg "-name name"] \
      [opt [arg "-validity valid"]]]

Add name to a recipient token.

[call [cmd "\$recipient"] \
      [arg "list"]]

Return a list of recipients in a recipient token.

[list_end]

[section "ASYNCHRONOUS MODE"]

Many GPG subcommands may posess [arg "-command"] options. It turns
asynchronous mode on and specifies a callback which is called to return
operation result. This means that the command returns immediately, the pipe
to GPG is switched to non-blocking mode and data from it is read only when
it is available. After the operation is completed the callback is invoked
with appended status (\"ok\" or \"error\") and the operation result in the
same form as it would be returned in synchronous mode.

[section EXAMPLES]

Encrypt the word Hello using a symmetric encryption using
passphrase "abcdefgh":

[comment {Spaces after trailing \ are essential}]
[example {
proc pass {args} {return abcdefgh}
set gpg [::gpg::new]
$gpg set -property armor -value true
$gpg set -property encoding -value utf-8
$gpg set -property passphrase-callback -value pass
puts [$gpg encrypt -input Hello]
$gpg free
}]

[section "AUTHORS"]
Sergei Golovan

[keywords Tcl GnuPG]
[comment { vim: set ft=tcl ts=8 sw=4 sts=4 et: }]
[manpage_end]
